home *** CD-ROM | disk | FTP | other *** search
/ Visual Cafe 3 / Visual Cafe 3.ISO / Vcafe / JFC.bin / Document.java < prev    next >
Text File  |  1998-06-30  |  10KB  |  268 lines
  1. /*
  2.  * @(#)Document.java    1.26 98/04/09
  3.  * 
  4.  * Copyright (c) 1997 Sun Microsystems, Inc. All Rights Reserved.
  5.  * 
  6.  * This software is the confidential and proprietary information of Sun
  7.  * Microsystems, Inc. ("Confidential Information").  You shall not
  8.  * disclose such Confidential Information and shall use it only in
  9.  * accordance with the terms of the license agreement you entered into
  10.  * with Sun.
  11.  * 
  12.  * SUN MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF THE
  13.  * SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
  14.  * IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
  15.  * PURPOSE, OR NON-INFRINGEMENT. SUN SHALL NOT BE LIABLE FOR ANY DAMAGES
  16.  * SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR DISTRIBUTING
  17.  * THIS SOFTWARE OR ITS DERIVATIVES.
  18.  * 
  19.  */
  20. package com.sun.java.swing.text;
  21.  
  22. import com.sun.java.swing.event.*;
  23.  
  24. /**
  25.  * <p>
  26.  * Container for text that supports editing and provides notification of
  27.  * changes (serves as the model in an MVC relationship).  Support is 
  28.  * provided to mark up the text with structure that tracks changes.  The
  29.  * unit of structure is called an element.  Views will typically be built
  30.  * from an element structure.  Each element can have an arbitrary set of
  31.  * attributes associated with it.  The interface itself is intended to be
  32.  * free of any policy for structure that is provided, as the nature of 
  33.  * the document structure should be determined by the implementation.  
  34.  * </p>
  35.  * <p align=center><img src="doc-files/document.gif"></p>
  36.  * <p>
  37.  * Typically there will be only one document structure, but the interface
  38.  * supports building an arbitrary number of structural projections over the 
  39.  * text data. The document can have multiple root elements to support 
  40.  * multiple document structures.  Some examples might be:
  41.  * </p>
  42.  * <ul>
  43.  * <li>Logical document structure.
  44.  * <li>View projections.
  45.  * <li>Lexical token streams.
  46.  * <li>Parse trees.
  47.  * <li>Conversions to formats other than the native format.
  48.  * <li>Modification specifications.
  49.  * <li>Annotations.
  50.  * </ul>
  51.  *
  52.  * @author  Timothy Prinzing
  53.  * @version 1.26 04/09/98
  54.  *
  55.  * @see DocumentEvent
  56.  * @see DocumentListener
  57.  * @see Element
  58.  * @see Position
  59.  * @see AttributeSet
  60.  */
  61. public interface Document {
  62.  
  63.     /**
  64.      * Returns number of characters of content currently 
  65.      * in the document.
  66.      *
  67.      * @return number of characters >= 0
  68.      */
  69.     public int getLength();
  70.  
  71.     /**
  72.      * Registers the given observer to begin receiving notifications
  73.      * when changes are made to the document.
  74.      *
  75.      * @param listener the observer to register
  76.      * @see Document#removeDocumentListener
  77.      */
  78.     public void addDocumentListener(DocumentListener listener);
  79.  
  80.     /**
  81.      * Unregisters the given observer from the notification list
  82.      * so it will no longer receive change updates.  
  83.      *
  84.      * @param listener the observer to register
  85.      * @see Document#addDocumentListener
  86.      */
  87.     public void removeDocumentListener(DocumentListener listener);
  88.  
  89.     /**
  90.      * Registers the given observer to begin receiving notifications
  91.      * when undoable edits are made to the document.
  92.      *
  93.      * @param listener the observer to register
  94.      * @see com.sun.java.swing.event.UndoableEditEvent
  95.      */
  96.     public void addUndoableEditListener(UndoableEditListener listener);
  97.  
  98.     /**
  99.      * Unregisters the given observer from the notification list
  100.      * so it will no longer receive updates.
  101.      *
  102.      * @param listener the observer to register
  103.      * @see com.sun.java.swing.event.UndoableEditEvent
  104.      */
  105.     public void removeUndoableEditListener(UndoableEditListener listener);
  106.  
  107.     /**
  108.      * Gets properties associated with the document.  Allows one to
  109.      * store things like the document title, author, etc.
  110.      *
  111.      * @param key a non-null property
  112.      * @return the properties
  113.      */
  114.     public Object getProperty(Object key);
  115.  
  116.     /**
  117.      * Puts a new property on the list.
  118.      *
  119.      * @param key the non-null property key
  120.      * @param value the property value
  121.      */
  122.     public void putProperty(Object key, Object value);
  123.  
  124.     /**
  125.      * Removes a portion of the content of the document.  This
  126.      * will cause notification to be sent to the observers of
  127.      * the document (unless an exception is thrown).
  128.      *
  129.      * @param offs  the offset from the begining >= 0
  130.      * @param len   the number of characters to remove >= 0
  131.      * @exception BadLocationException  some portion of the removal range
  132.      *   was not a valid part of the document.  The location in the exception
  133.      *   is the first bad position encountered.
  134.      * @see DocumentEvent
  135.      * @see DocumentListener
  136.      */
  137.     public void remove(int offs, int len) throws BadLocationException;
  138.  
  139.     /**
  140.      * Inserts a string of content.  This will cause the observers of the
  141.      * the document to be notified, unless an exception is thrown.
  142.      *
  143.      * A position marks a location in the document between items.  
  144.      *
  145.      * If the attributes that have been defined exactly match the
  146.      * current attributes defined at the position, the element 
  147.      * representing the content at that position will simply be expanded.  
  148.      * If the attributes defined are different, a new content element
  149.      * will be created that matches the attributes.  Does nothing with null
  150.      * or empty strings.
  151.      *
  152.      * @param offset  the offset into the document to insert the content >= 0.
  153.      *    All positions that track change at or after the given location 
  154.      *    will move.  
  155.      * @param str    the string to insert
  156.      * @param a      the attributes to associate with the inserted
  157.      *   content.  This may be null if there are no attributes.
  158.      * @exception BadLocationException  the given insert position is not a valid 
  159.      * position within the document
  160.      * @see DocumentEvent
  161.      * @see DocumentListener
  162.      */
  163.     public void insertString(int offset, String str, AttributeSet a) throws BadLocationException;
  164.  
  165.     /**
  166.      * Fetches the text contained within the given portion 
  167.      * of the document.
  168.      *
  169.      * @param offset  the offset into the document representing the desired 
  170.      *   start of the text >= 0
  171.      * @param length  the length of the desired string >= 0
  172.      * @return the text, in a String of length >= 0
  173.      * @exception BadLocationException  some portion of the given range
  174.      *   was not a valid part of the document.  The location in the exception
  175.      *   is the first bad position encountered.
  176.      */
  177.     public String getText(int offset, int length) throws BadLocationException;
  178.  
  179.     /**
  180.      * Fetches the text contained within the given portion 
  181.      * of the document.
  182.      *
  183.      * @param offset  the offset into the document representing the desired 
  184.      *   start of the text >= 0
  185.      * @param length  the length of the desired string >= 0
  186.      * @param txt the Segment object to return the text in
  187.      *
  188.      * @exception BadLocationException  Some portion of the given range
  189.      *   was not a valid part of the document.  The location in the exception
  190.      *   is the first bad position encountered.
  191.      */
  192.     public void getText(int offset, int length, Segment txt) throws BadLocationException;
  193.  
  194.     /**
  195.      * Returns a position that represents the start of the document.  The 
  196.      * position returned can be counted on to track change and stay 
  197.      * located at the beginning of the document.
  198.      *
  199.      * @return the position
  200.      */
  201.     public Position getStartPosition();
  202.     
  203.     /**
  204.      * Returns a position that represents the end of the document.  The
  205.      * position returned can be counted on to track change and stay 
  206.      * located at the end of the document.
  207.      *
  208.      * @return the position
  209.      */
  210.     public Position getEndPosition();
  211.  
  212.     /**
  213.      * Returns a position that will track change as the document
  214.      * is altered.  If the relative position pos is null, the
  215.      * start of the document will be used.
  216.      *
  217.      * @param offs  the offset from the start of the document >= 0
  218.      * @return the position
  219.      * @exception BadLocationException  if the given position does not
  220.      *   represent a valid location in the associated document
  221.      */
  222.     public Position createPosition(int offs) throws BadLocationException;
  223.  
  224.     /**
  225.      * Returns all of the root elements that are defined.
  226.      *
  227.      * @return the root element
  228.      */
  229.     public Element[] getRootElements();
  230.  
  231.     /**
  232.      * Returns the root element that views should be based upon,
  233.      * unless some other mechanism for assigning views to element
  234.      * structures is provided.
  235.      *
  236.      * @return the root element
  237.      */
  238.     public Element getDefaultRootElement();
  239.  
  240.     /**
  241.      * This allows the model to be safely rendered in the presence
  242.      * of currency, if the model supports being updated asynchronously.
  243.      * The given runnable will be executed in a way that allows it
  244.      * to safely read the model with no changes while the runnable
  245.      * is being executed.  The runnable itself may <em>not</em>
  246.      * make any mutations.  
  247.      *
  248.      * @param r a Runnable used to render the model
  249.      */
  250.     public void render(Runnable r);
  251.  
  252.     /**
  253.      * The property name for the description of the stream
  254.      * used to initialize the document.  This should be used
  255.      * if the document was initialized from a stream and 
  256.      * anything is known about the stream.
  257.      */
  258.     public static final String StreamDescriptionProperty = "stream";
  259.  
  260.     /**
  261.      * The property name for the title of the document, if 
  262.      * there is one.
  263.      */
  264.     public static final String TitleProperty = "title";
  265.  
  266.  
  267. }
  268.